home *** CD-ROM | disk | FTP | other *** search
/ Aminet 24 / Aminet 24 (1998)(GTI - Schatztruhe)[!][Apr 1998].iso / Aminet / dev / c / cxref_1_4a.lha / README < prev    next >
Text File  |  1997-12-07  |  17KB  |  345 lines
  1.           C Cross Referencing & Documenting tool. Version 1.4a - cxref
  2.           ============================================================
  3.  
  4. A program that can automatically generate documentation and cross references for
  5. a C program.
  6.  
  7. The input is any C program with appropriate comments and the output is LaTeX or
  8. HTML files.
  9.  
  10. --------------------------------------------------------------------------------
  11. ------------------------------- Program Options --------------------------------
  12. --------------------------------------------------------------------------------
  13.  
  14. The name of the program is cxref.
  15.  
  16. Usage: cxref filename [ ... filename]
  17.              [-Odirname] [-Nbasename] [-Rdirname]
  18.              [-all-comments] [-no-comments]
  19.              [-verbatim-comments] [-block-comments]
  20.              [-xref[-all][-file][-func][-var][-type]]
  21.              [-warn[-all][-comment][-xref]]
  22.              [-index[-all][-file][-func][-var][-type]]
  23.              [-raw]
  24.              [-latex|-latex2e]
  25.              [-html]
  26.              [-Idirname] [-Ddefine] [-Udefine]
  27.              [-CPP cpp_program] [-- cpp_arg [ ... cpp_arg]]
  28.  
  29. Usage: cxref filename [ ... filename] -delete
  30.              [-Odirname] [-Nbasename] [-Rdirname]
  31.  
  32.  
  33. filename        The name of the file to document, any number of files may be
  34.                 documented at a time.
  35.  
  36. -delete         The files named are to be deleted from the output directory and
  37.                 their entries in the cross reference database and main output
  38.                 files are to be removed.
  39.  
  40. -Odirname       The name of a directory to use for the output latex files and
  41.                 the location of the cross reference files that are created.
  42.  
  43. -Nbasename      The name to use for the first part of the output and cross
  44.                 reference files instead of cxref, the file extensions remain
  45.                 the same.
  46.  
  47. -Rdirname       When the source files are in more than one directory, set
  48.                 dirname to the name of the root directory of the source tree
  49.                 (use relative path if easier e.g. `-R../..').  This will then
  50.                 run cxref from that root directory and the `-Odirname' must be
  51.                 relative to that directory.
  52.  
  53. -all-comments   In case you think that the existing comments might work,
  54.                 (see below for description of special comments).
  55.                 [Danger! This option can produce weird results.]
  56.  
  57. -no-comments    Ignores all comments, useful if you just want the cross
  58.                 references and not the documentation.
  59.  
  60. -verbatim-comments   When the comments that you have in the code are formatted
  61.                 in a predetermined style that you want to preserve on the
  62.                 output, this option will force them not to be reformatted.
  63.                 [Note, this is for file and function comments only.]
  64.  
  65. -block-comments When the comments in the program are formatted in the `block'
  66.                 style (with a leading `*' character on every line), this option
  67.                 will remove that character from the output.
  68.                 [Works for a single `*', `+', `|' or `:' on each line.]
  69.  
  70. -xref           Produce cross referencing information (see below).
  71.                 -all    All cross references.
  72.                 -file   Cross references for files.
  73.                 -func   Cross references for functions.
  74.                 -var    Cross references for variables.
  75.                 -type   Cross references for types.
  76.  
  77. -warn           Produce warnings, the options must be concatenated together:
  78.                 -all       All warnings.
  79.                 -comment   Warn of missing comments.
  80.                 -xref      Warn of missing cross references.
  81.  
  82. -index          Produce a cross reference index, the options must be
  83.                 concatenated together:
  84.                 -all    All indexes.
  85.                 -file   Index of files.
  86.                 -func   Index of functions.
  87.                 -var    Index of variables.
  88.                 -type   Index of types.
  89.  
  90. -raw            Produce a raw form of output, not really of much use except
  91.                 with -warn.
  92.  
  93. -latex          Produce a LaTeX file to document each of the source files and
  94.                 also an extra file that includes each of these files.
  95. -latex2e        Produce the LaTeX file described above for use with the
  96.                 LaTeX2e version of LaTeX.
  97.  
  98. -html           Produce an HTML file to document each of the source files and
  99.                 a main file to reference each of these files.
  100.  
  101. -Idirname       GCC option to specify the path for include files.
  102. -Ddefine        GCC option to define a pre-processor symbol.
  103. -Udefine        GCC option to undefine a pre-processor symbol.
  104.  
  105. -CPP program    The name of the program to use instead of the compile time
  106.                 default. The program must be able to perform all of the actions
  107.                 that `gcc -E -C -dD' does to work.  If the program takes
  108.                 arguments then the whole thing needs to be in quotes so that it
  109.                 is interpreted as a single argument to cxref.
  110.  
  111. -- arg ... arg  Extra arguments to be passed to the pre-processor can be placed
  112.                 after the `--' separator.
  113.  
  114. --------------------------------------------------------------------------------
  115. ----------------------- C Compiler Replacement cxref-cc ------------------------
  116. --------------------------------------------------------------------------------
  117.  
  118. To simplify using cxref on existing source code, there is now a shell script
  119. that will call the C compiler and then call cxref to process the source file.
  120. This means that it can be used as a drop in replacement for CC in Makefiles and
  121. the like.
  122.  
  123. Usage: cxref-cc [usual cc options]
  124.  
  125. The name of the source file is extracted from the list of options as well as the
  126. `-D*', `-I*', `-U*' flags and when the C compiler exits succesfully cxref will
  127. be called.  The name of the C compiler to use is controlled by the CXREFCC
  128. environment variable, or if this is not set then the CC environment variable, or
  129. failing this just gcc.
  130.  
  131. Using this script requires the use of a `.cxref' configuration file to contain
  132. the options since there is nowhere to put the options on the command line for
  133. the C compiler.
  134.  
  135. This will only cross-reference and document the C source files since they are
  136. the only ones that are compiled, but it will make sure that they are
  137. cross-referenced with the correct options etc.
  138.  
  139. --------------------------------------------------------------------------------
  140. ----------------------- Cxref configuration File .cxref ------------------------
  141. --------------------------------------------------------------------------------
  142.  
  143. These command line arguments can also be put into a file named `.cxref' instead
  144. of on the command line.  When cxref is run the arguments to the program are
  145. interpreted in the following order.
  146.  
  147. 1) Those on the command line.
  148. 2) Those in the `.cxref' file in the current directory.
  149. 3) Those in the `.cxref' file in the source tree root specified by `-R'.
  150.  
  151. This means that in a multi-directory source tree, each sub-directory can have a
  152. `.cxref' file containing just the line `-R..' or appropriate.  The main
  153. directory can have a `.cxref' file containing the remainder of the options.
  154. This removes completely the need to have any options on the command line apart
  155. from the source file names.
  156.  
  157. The format of the `.cxref' file is any number of lines, each one containing a
  158. single command line argument (equivalent to one of the argv).  The only options
  159. that cannot be used are the names of source files themselves and the `-delete'
  160. option.  Blank lines are ignored and lines starting with a '#' are comments.
  161.  
  162. --------------------------------------------------------------------------------
  163. ------------------------ Program Documentation Comments ------------------------
  164. --------------------------------------------------------------------------------
  165.  
  166. The documentation for the program is produced from comments in the code that are
  167. appropriately formatted.  The cross referencing comes from the code itself and
  168. requires no extra work.
  169.  
  170. The special comments are `/**** ****/' (for a file) and `/*++